<!-- ***************************************************************** -->
<chapter id="ch-DragAngDrop">
-<title>Drag and Drop (DND)</title>
+<title>Drag-and-drop (DND)</title>
-<para>GTK+ has a high level set of functions for doing inter-window
-communication using the drag and drop system on top of the low level
-Xdnd and Motif protocols.</para>
+<para>GTK+ has a high level set of functions for doing inter-process
+communication via the drag-and-drop system. GTK+ can perform
+drag-and-drop on top of the low level Xdnd and Motif drag-and-drop
+protocols.</para>
<!-- ----------------------------------------------------------------- -->
<sect1 id="sec-DragAndDropOverview">
<title>Overview</title>
-<para>An application capable of GTK+ drag and drop first defines and sets up
-the GTK+ widget(s) for drag and drop. Each widget can be a source
-and/or destination for drag and drop. Note that these GTK+ widgets must have
-an associated X Window, check using GTK_WIDGET_NO_WINDOW(wid)).</para>
+<para>An application capable of GTK+ drag-and-drop first defines and sets up
+the GTK+ widget(s) for drag-and-drop. Each widget can be a source
+and/or destination for drag-and-drop. Note that these GTK+ widgets must have
+an associated X Window, check using GTK_WIDGET_NO_WINDOW(widget)).</para>
<para>Source widgets can send out drag data, thus allowing the user to drag
things off of them, while destination widgets can receive drag data.
-Drag and drop destinations can limit who they accept drag data from,
+Drag-and-drop destinations can limit who they accept drag data from,
e.g. the same application or any application (including itself).</para>
<para>Sending and receiving drop data makes use of GTK+ signals.
request (for the source widget) and data received signal handler (for
the target widget). Additional signal handers can be connected if you
want to know when a drag begins (at the very instant it starts), to
-when a drop is made, and when the entire drag and drop procedure has
+when a drop is made, and when the entire drag-and-drop procedure has
ended (successfully or not).</para>
<para>Your application will need to provide data for source widgets when
destination widgets they will need a drop data received signal
handler. </para>
-<para>So a typical drag and drop cycle would look as follows:</para>
+<para>So a typical drag-and-drop cycle would look as follows:</para>
<orderedlist>
<listitem><simpara> Drag begins.</simpara>
</listitem>
</listitem>
<listitem><simpara> Drag data delete (if the drag was a move).</simpara>
</listitem>
-<listitem><simpara> Drag and drop procedure done.</simpara>
+<listitem><simpara> Drag-and-drop procedure done.</simpara>
</listitem>
</orderedlist>
<listitem><simpara> Drag action type (ie GDK_ACTION_COPY, GDK_ACTION_MOVE).</simpara>
</listitem>
-<listitem><simpara> Client specified arbitrary drag and drop type (a
-gchar *name and a gint info id number pair).</simpara>
+<listitem><simpara> Client specified arbitrary drag-and-drop type (a name and number pair).</simpara>
</listitem>
<listitem><simpara> Sent and received data format type.</simpara>
<para>Drag actions are quite obvious, they specify if the widget can
drag with the specified action(s), e.g. GDK_ACTION_COPY and/or
-GDK_ACTION_MOVE. A GDK_ACTION_COPY would be a typical drag and drop
+GDK_ACTION_MOVE. A GDK_ACTION_COPY would be a typical drag-and-drop
without the source data being deleted while GDK_ACTION_MOVE would be
just like GDK_ACTION_COPY but the source data will be 'suggested' to be
deleted after the received signal handler is called. There are
additional drag actions including GDK_ACTION_LINK which you may want to
-look into when you get to more advanced levels of drag and drop.</para>
+look into when you get to more advanced levels of drag-and-drop.</para>
-<para>The client specified arbitrary drag and drop type is much more
+<para>The client specified arbitrary drag-and-drop type is much more
flexible, because your application will be defining and checking for
that specifically. You will need to set up your destination widgets to
-receive certain drag and drop types by specifying a name and/or number.
+receive certain drag-and-drop types by specifying a name and/or number.
It would be more reliable to use a name since another application may
just happen to use the same number for an entirely different
meaning.</para>
<sect1 id="sec-DragAndDropFunctions">
<title>Functions</title>
-<para>Setting up source widget:</para>
+<sect2 id="sec-DNDSourceWidgets">
+<title>Setting up the source widget</title>
+<para>The function <literal>gtk_drag_source_set()</literal> specifies a
+set of target types for a drag operation on a widget.</para>
+
+<programlisting role="C">
+void gtk_drag_source_set( GtkWidget *widget,
+ GdkModifierType start_button_mask,
+ const GtkTargetEntry *targets,
+ gint n_targets,
+ GdkDragAction actions );
+</programlisting>
+
+<para>The parameters signify the following:</para>
<itemizedlist>
-<listitem><simpara> <literal>gtk_drag_source_set()</literal> specifies a
-set of target types for a drag operation on a widget.</simpara>
+<listitem><simpara><literal>widget</literal> specifies the drag source
+widget</simpara>
+</listitem>
+<listitem><simpara><literal>start_button_mask</literal> specifies a
+bitmask of buttons that can start the drag (e.g. GDK_BUTTON1_MASK)</simpara>
+</listitem>
+<listitem><simpara><literal>targets</literal> specifies a table of
+target data types the drag will support</simpara>
+</listitem>
+<listitem><simpara><literal>n_targets</literal> specifies the number of
+targets above</simpara>
+</listitem>
+<listitem><simpara><literal>actions</literal> specifies a bitmask of
+possible actions for a drag from this window</simpara>
</listitem>
-<listitem><simpara> <literal>gtk_drag_source_unset()</literal> specifies
-that the widget is to no longer perform drag operations.</simpara>
-</listitem>
</itemizedlist>
-<para>Signals on the source widget:</para>
+<para>The <literal>targets</literal> parameter is an array of the
+following structure:</para>
+
+<programlisting role="C">
+struct GtkTargetEntry {
+ gchar *target;
+ guint flags;
+ guint info;
+ };
+</programlisting>
+
+<para>The fields specify a string representing the drag type, optional
+flags and application assigned integer identifier.</para>
+
+<para>If a widget is no longer required to act as a source for
+drag-and-drop operations, the function
+<literal>gtk_drag_source_unset()</literal> can be used to remove a set
+of drag-and-drop target types.</para>
+
+<programlisting role="C">
+void gtk_drag_source_unset( GtkWidget *widget );
+</programlisting>
+
+</sect2>
+
+<sect2 id="sec-SignalsOnSourceWidgets">
+<title>Signals on the source widget:</title>
<itemizedlist>
<listitem><simpara> drag_begin - prototype: void (*drag_begin)(GtkWidget
</listitem>
</itemizedlist>
-<para>Setting up destination widget:</para>
+</sect2>
+
+<sect2 id="sec-DNDDestWidgets">
+<title>Setting up a destination widget:</title>
<itemizedlist>
<listitem><simpara> <literal> gtk_drag_dest_set()</literal> specifies
</listitem>
</itemizedlist>
-<para>Signals on the destination widget:</para>
+</sect2>
+
+<sect2 id="sec-SignalsOnDestWidgets">
+<title>Signals on the destination widget:</title>
<itemizedlist>
<listitem><simpara> drag_data_received - prototype: void (*drag_data_received)(GtkWidget *widget, GdkDragContext
</listitem>
</itemizedlist>
+</sect2>
</sect1>
</chapter>
projects / gtk4.git / commitdiff